feat(proxy): support OAuth callers for Codex Live Voice - #1577

To use Codex here, create an environment for this repo.

@codex review

@codex review

@codex review

@codex review

@codex review

Codex Review: Didn't find any major issues. Bravo.

Reviewed commit: 5428e89f46

@codex review

@codex review

Codex Review: Didn't find any major issues. Bravo.

Reviewed commit: 845bfb43dc

Traced the admission paths against main; the fail-closed properties hold up:

• With global API-key auth enabled, the non-sk-clb- lane feeds a null bearer into validate_proxy_api_key_authorization (app/modules/proxy/realtime_auth.py, _validate_keyless_origin), so it 401s before any policy lookup — verified against app/core/auth/dependencies.py:70-87.
• Inactive or empty policy 403s via RealtimeCallerScope.for_oauth, and get_active_allowed_account_ids re-filters Account.status == ACTIVE on every connection, so a paused account drops out of the pool without a policy edit.
• Registered-key affinity material stays api_key.id, so digests are byte-identical to today's (pinned by test_realtime_call_affinity_key_preserves_registered_key_digest_bytes) — existing bound calls survive the deploy.
• Migration head chains off 20260803_000000_merge_... (current main head) with up/down coverage.

Two points that are owner calls rather than defects:

1. This flips the feat(proxy): support Codex Live Voice sideband #1492 contract. Live routes were "always require a registered proxy key, even when ordinary proxy auth is disabled"; now, in keyless mode, any origin-admitted caller with an arbitrary unverified bearer + chatgpt-account-id header consumes the policy pool, with no per-caller limits (unlike validate_codex_usage_identity, the lane deliberately never verifies the bearer upstream — test_realtime_call_create_oauth_scope_selects_only_allowed_account asserts fetch_usage stays unreachable). That matches the ordinary zero-key proxy trust level and is default-off, but it turns Live from key-gated to origin-gated and deserves explicit sign-off.
2. Affinity material HMACs the raw access token (_oauth_live_affinity_scope_material), so an OAuth token refresh mid-call orphans the sideband binding (404, new call required). Documented in docs/live-voice.md; fine for short calls, just credential-lifetime coupled.

Interaction note: OAuth Live traffic carries api_key=None, so if #1536's per-key fair-share stream admission lands, keyless Live callers sit outside its accounting — worth reconciling whichever merges second.

Thanks for tracing the admission paths and calling out the owner decisions. I confirm the intended boundaries:

1. Origin-gated OAuth Live is intentional. The feature remains default-off and reuses the existing zero-key origin boundary. The bearer and normalized chatgpt-account-id remain required request fields, while neither is verified through the OpenAI usage endpoint. The network boundary is the authorization decision; the locally unverified account header supplies only an ownership namespace. Admitted clients presenting the same normalized account ID share that namespace and still need the bounded, high-entropy call ID to attach. Deployments requiring caller-level isolation continue to use registered Proxy API Keys.

2. Bearer refresh now preserves an existing call binding. Commit 613d5d9f removes the raw bearer from OAuth Live affinity and derives the purpose-separated HMAC from only the normalized chatgpt-account-id. A changed bearer with the same account ID resolves the same call-owner digest; a changed account ID or encryption key resolves a different scope. Unit and integration coverage exercise call creation with one bearer and sideband attachment with another. A real Codex Desktop E2E also replaced the bearer between call creation and sideband forwarding; the sideband connected to the same call and completed an audible Live Voice response.

3. The feat(proxy): congestion-aware per-API-key fair-share stream admission #1536 interaction is explicit. OAuth Live intentionally keeps api_key=None. Registered Proxy API Key traffic participates in per-key fair-share, while keyless OAuth Live bypasses per-key accounting. Its sideband still acquires the normal Account stream lease, counts toward pool inflight, and remains subject to the serving Account's stream-capacity limit. The default-off, origin-gated v1 model accepts trusted keyless callers consuming shared pool capacity and does not synthesize an API Key principal.

The PR description, user docs, change-level OpenSpec, and main realtime-api-compat spec/context now describe these final semantics. Local make ci-fast, strict OpenSpec validation (49/49 specs), strict MkDocs, the focused OAuth Live suite (58 passed), and local Codex Review are clean.

@codex review

Codex Review: Didn't find any major issues. You're on a roll.

Reviewed commit: 613d5d9f38

The current-head CI completed with every code, test, migration, frontend, and Docker job green. The only failure was Package (build) before the package step ran: setup-uv timed out after 5 seconds while fetching https://raw.githubusercontent.com/astral-sh/versions/main/v1/uv.ndjson. Other setup-uv jobs in the same run succeeded, so this is a runner/download transient rather than a code failure. I attempted gh run rerun 30895394704 --failed, but GitHub requires repository admin rights. Could a maintainer rerun the failed jobs for run 30895394704?

Maintainer decision on the keyless lane — thanks for the careful implementation (the fail-closed properties I traced earlier all hold, and the codex passes are clean), but as designed this can't merge: an unverified bearer plus an unverified chatgpt-account-id header cannot be the admission boundary for consuming the operator's upstream pool. Origin ACLs are a network control, not caller authentication, and "same normalized account ID shares one ownership namespace" means any origin-admitted caller can both consume pooled quota and co-occupy another caller's namespace by presenting the same header.

Direction, in priority order:

1. First, establish whether the keyless lane is even necessary. Investigate whether the official Codex Live Voice client can carry a registered key at all — an Authorization: Bearer sk-clb-* substitution, an extra custom header, a query parameter, or client config. If any of those work, the existing registered-key lane already covers this use case end-to-end (limits, attribution, affinity) and we should drop the keyless lane entirely. Please document findings on this PR (client version, code pointers or captures) before further review rounds.

2. If the client genuinely cannot pass a key, admission must be tied to something the LB can verify rather than trust:

   • Verified whitelist against LB-registered accounts: require the presented chatgpt-account-id to match an upstream account registered in this LB (or an operator-maintained allowlist of account IDs), and validate the bearer upstream (a lightweight authenticated call against the OpenAI side) instead of accepting it as an opaque namespace seed; or
   • An explicit enrollment flow: first-use registration that binds an OAuth caller to an LB-managed identity — a per-caller record with its own limits, attribution, and revocation — effectively minting a key-equivalent identity for keyless clients, rather than a global anonymous namespace behind one switch.

In all variants the bar is the same: per-caller identity, per-caller limits, revocability, and attribution. A default-off global policy doesn't substitute for that bar; it only limits the blast radius of not having it.

Two housekeeping notes: I'll rerun the transient Package (build) failure you flagged, and please stop re-triggering @codex review — the bot is rate-limited repo-wide and repeated triggers starve other PRs.

To use Codex here, create an environment for this repo.

@Soju06

Thanks — before rewriting the implementation, I would like to confirm the identity model and admission boundary with you.

Client finding

I tested the current official Codex Desktop build 26.727.51351 (6119):

• With the built-in openai provider and OAuth auth state, Codex exposes the Live Voice entry.
• Switching the Desktop auth state to a registered sk-clb-* key successfully routes ordinary /responses traffic through codex-lb.
• In that API-key auth state, Codex Desktop hides the Live Voice entry before any call-create or sideband request is emitted.
• I could not find a supported setting in this build that preserves the OAuth UI state while attaching a separate Proxy API Key to Live call-create and sideband requests.

The registered-key lane therefore does not currently cover the built-in openai provider use case. I will add the sanitized client configuration and captures to the PR documentation.

Proposed OAuth identity model

I propose replacing the origin-gated anonymous OAuth scope with an explicitly enrolled and upstream-verified caller principal:

1. Add a first-class OAuthLiveCaller record linked to an LB-registered account.
2. Identify the caller by the stable per-seat identity (chatgpt_user_id / token sub) together with the ChatGPT workspace/account identity.
3. Validate each new bearer credential through the existing upstream usage-identity path and require it to resolve to the active enrolled caller.
4. Map successful verification to a persistent principal ID such as oauth:<oauth_live_caller_id>.
5. Bind call ownership to that principal ID. A refreshed bearer revalidates and resolves to the same principal, preserving the existing call binding.
6. Keep the serving upstream-account pool separate from the caller identity.
7. Treat the existing origin ACL as defense in depth only.

Successful credential validation would use a bounded, short-lived cache keyed by an HMAC token fingerprint. Raw bearer credentials would remain absent from persistence and logs.

Limits, attribution, and revocation

RealtimeCallerScope would carry a common principal_id:

• Registered key: key:<api_key_id>
• Enrolled OAuth caller: oauth:<oauth_live_caller_id>

Affinity, admission accounting, and request attribution would use this stable principal ID. Each OAuth caller record would be independently revocable and would have its own Live admission limits. This also provides a clean integration point for #1536 without assigning OAuth traffic an anonymous api_key=None identity.

Before I implement this rewrite, could you confirm:

1. Does a first-class OAuthLiveCaller plus a shared admission-principal abstraction match the identity boundary you expect, or would you prefer OAuth enrollment to reuse/link directly to an existing API Key policy record?
2. Is the existing upstream usage-identity call acceptable as bearer proof when combined with per-seat ID and workspace matching?
3. For the initial per-caller limit contract, would a call-create rate limit plus an active Live sideband cap be sufficient, or should OAuth callers reuse the full API Key limit/fair-share model from the first version?

I will wait for your direction before changing the identity model or triggering further automated review.

Thanks for the client testing — I verified the finding against the open-source client core, and it changes the conclusion rather than supporting it.

The narrow observation is correct: with the built-in openai provider, switching the auth state to an API key drops the ChatGPT account state (account_state() in codex-rs/model-provider/src/provider.rs reports ProviderAccount::ApiKey), so account-gated entries including Live Voice disappear.

But "the registered-key lane does not cover the built-in openai provider use case" contradicts this PR's own artifacts. docs/live-voice.md (Registered Proxy API Key profile, lines 60-82) documents a custom provider with requires_openai_auth = true plus env_key, and your manual acceptance matrix in the PR description records Live Voice as Passed under that profile. The client mechanics confirm why it works:

• provider_uses_first_party_auth_path (codex-rs/model-provider/src/provider.rs) is false once env_key is set, so request credentials resolve through bearer_auth_for_provider (codex-rs/model-provider/src/auth.rs) — the sk-clb-* bearer — on every request.
• create_realtime_call_with_headers (codex-rs/core/src/client.rs) reuses the same resolved auth for call creation and for sideband_websocket_auth_headers, so both Live legs carry the registered key.
• requires_openai_auth = true keeps the ChatGPT login/account state — and therefore the Live Voice entry — visible while the wire credential is the key.

"Keep model_provider = \"openai\" unmodified" is not a real constraint either: the OAuth profile already requires config.toml edits for both experimental realtime base URLs, so the registered-key profile costs one provider block and one env var, and gains per-caller identity, limits, attribution, and revocation for free.

So option 1 from my previous comment appears satisfied by the current client. Two asks before we go further:

1. Please re-run the registered-key Live E2E against main (not this branch — main already carries the identical route set and required-key admission from feat(proxy): support Codex Live Voice sideband #1492; this PR's app/modules/proxy/api.py delta only swaps admission resolution) and post the client version plus sanitized config. If it passes, the keyless lane is unnecessary and this PR should be reduced to the client-profile documentation, which is genuinely valuable on its own.
2. Please reconcile the discrepancy between your 08-04 comment ("could not find a supported setting") and the passed registered-key acceptance row — e.g. whether that row was actually exercised with the OAuth policy enabled or over the WebSocket transport.

If the E2E fails against main for a reason we haven't identified, or if key distribution turns out to be operationally unacceptable for the target deployments, then your enrollment sketch is the right shape (per-caller record, upstream verification via the usage-identity path, stable principal_id, per-caller limits and revocation) — you effectively built the verification module once already (app/core/auth/codex_oauth_identity.py, removed in 0d3ceef), so restoring it must also fix the hazards flagged in the earlier review rounds: bounded validation-task concurrency instead of detached asyncio.shield tasks, identity-cache invalidation on account pause/delete, and unchanged membership checks for /api/codex/usage. I'll answer your three identity-model questions explicitly if we end up on that path.

Maintainer decision (owner-confirmed): option 1 is satisfied — we're dropping the keyless OAuth lane. Concretely:

1. Please re-verify the registered-key Live Voice E2E against current main (not this branch — main already carries the complete registered-key Live lane from feat(proxy): support Codex Live Voice sideband #1492; this branch's route set is identical) using the custom-provider profile from your own docs/live-voice.md (requires_openai_auth = true + env_key), and post the sanitized client config here.
2. Re-scope this PR to the client-profile documentation (plus any admission-resolution cleanup that stands alone without the keyless lane).
3. The enrollment/identity questions (Q1–Q3) are parked, not rejected — if a concrete key-distribution-free deployment need resurfaces, we'll take the enrollment path with the hazards above as the entry bar.